What's the idea behind this?

The idea is that I don't to implement local name resolution for C/C++ in QL 😅 So I simplified the necessary name resolution by requiring that there's only 1 local variable with the given name in the enclosing function (see the unique here which achieves this).

I guess this might be potentially confusing, because isAffectedByMacro/0 is not implemented as affectedbymacroexpansion(underlyingElement(this), _).

I agree. Do you have any suggestion for a better QLDoc?

What does this line achieve?

This relates the function f to the macro invocation mi. Otherwise, we don't know which function mi occurs in.

Ok, so why does this look at - what is effectively - the whole body of the function, and not just at the statement we're interested in?

We can do that as well. I guess we could do something like:

exists(Stmt stmt |
  stmt.isAffectedByMacro(mi) and
  f = stmt.getEnclosingFunction()
)

I only did the above since that didn't need me to existentially quantify a Stmt. But if you prefer the other thing I guess that's just as fine.

I don't think that really resolves the thing I have trouble wrapping my head around: Why do we need to refer to the function at all here? Why isn't it sufficient to look at the statement?

The statement isn't enough because of templates. Consider this scenario (let's ignore the uninstantiated function template for the discussion since we don't generate IR for that anyway):

1 | #define assert(x) ((void)0)
2 | 
3 | template<typename T>
4 | void f(int x) {
5 |   assert(x > 10);
6 | }
7 |
8 | // two arbitrary instantiations
9 | template void f<short>();
10| template void f<long>();

Now there are two (instantiated) function templates: f<short> and f<long> and they each have an ExprStmt for ((void)0) that we want to generate an assertion in the IR for.

To make it easy to figure out where we should place the assertion in the IR we require that the only thing on the line is the assertion.

However, the two ExprStmts have the same location. So the unique aggregate here require that there's a unique statement in the enclosing function where the macro is expanded.

So even though there are two ExprStmts on line 5 the condition "there is only 1 statement on the line" is still satisfied because we require it per-function. We could remove the function stuff, but then we wouldn't generate IR for the assertion since there would be two statements on the line (corresponding to the two ExprStmts from the two instantiations).

Does that make sense?

Yes, that makes sense.

What is the reason for using StmtParent here? what's the relevance of StmtExprs?

We want to capture the notion "this is the only entity we'll be generating IR for on this line (in this function)" to have a meaningful place to insert the assertion, and StmtParent (i.e., the union of Expr and Stmt) is the most general class which has an enclosing function.

What would change if we just check that there's just a single macro that affects the statement we're interested in? Instead of doing all this line business?

single macro = single macro of the kind we're interested in

I don't see how you would do that without doing all the line business. If you have:

#define assert(x)

void test(int x) {
  assert(x < 10);
}

I'm not sure how you relate the EmptyStmt to the MacroInvocation for assert(x < 10) without resorting to line matching. The affectedbymacroexpansion extensional on this DB only relates the macro invocation to the enclosing block statement:

Maybe that's a bug? If it related it to the macro invocation to the EmptyStmt (which is the statement we use as the TranslatedElement) then we could probably avoid line matching.